Skip to content

docs: streamline README getting started#280

Merged
zeitlinger merged 14 commits into
mainfrom
docs/linter-reference-overview
May 11, 2026
Merged

docs: streamline README getting started#280
zeitlinger merged 14 commits into
mainfrom
docs/linter-reference-overview

Conversation

@zeitlinger
Copy link
Copy Markdown
Member

@zeitlinger zeitlinger commented May 9, 2026 •
edited
Loading

What changed

  • streamlined README.md around a clearer Getting Started flow
  • moved detailed adaptive-run behavior out of the README and into docs/cli.md
  • simplified top-level docs navigation and trimmed low-value reference duplication
  • clarified agent guidance for mise run lint:fix
  • fixed CLI docs so --allow-fixed and --time are documented, including the FLINT_ALLOW_FIXED env var binding

Why

The README had grown less smooth to follow, especially around setup and where to find deeper details. This change keeps the README focused on onboarding and moves CLI-specific behavior into the CLI docs.

Impact

  • new users get a clearer install/use path
  • example setup now points to a realistic external repo
  • CLI-specific behavior is easier to find in docs/cli.md

Validation

  • mise run lint:fix

zeitlinger added 9 commits May 9, 2026 14:48
@zeitlinger
docs: improve linter reference overview
d37f9b9 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
readme
1ee4ee7 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
readme
34d26c8 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
readme
2e4a379 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
docs: streamline README getting started
38d369b 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
docs: generate CLI flags table from clap
268528c 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
docs: add JSON to files overview
ea807ef 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
chore: remove obsolete README renovate sync
a54bc61 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
chore: remove obsolete super-linter renovate rule
e6e5028 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger zeitlinger mentioned this pull request May 9, 2026
Closed
2 tasks
@zeitlinger zeitlinger marked this pull request as ready for review May 9, 2026 17:03
@zeitlinger zeitlinger requested a review from a team as a code owner May 9, 2026 17:03
Copilot AI review requested due to automatic review settings May 9, 2026 17:03
Copilot AI reviewed May 9, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR streamlines onboarding documentation by refocusing README.md on a clearer Getting Started flow and moving deeper operational/reference detail into dedicated docs, while updating the Rust registry/doc-generation logic to support the new doc structure (overview tables, upstream links, and generated CLI flag tables).

Changes:

  • Reworked README.md Getting Started and top-level docs navigation; moved “adaptive runs” details into docs/cli.md.
  • Added registry metadata (project_url, config_doc_url, overview placements) and updated doc generation/tests to render overview tables + linked linter/config references.
  • Added an auto-generated flint run flags table in docs/cli.md with sync tests.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
src/runner.rs Updates test helper Check struct literal to include new registry fields.
src/registry/types.rs Adds overview-related types and new Check metadata fields + builder methods.
src/registry/checks.rs Annotates built-in checks with upstream URLs and overview placements.
src/registry/tests.rs Reworks README/linters docs sync test to validate new overview tables and linked details.
src/registry/mod.rs Re-exports new overview types (with a new unused-import allowance).
src/main.rs Adds cli_docs_tests module and introduces env var binding for --allow-fixed.
src/linters/license_header.rs Adds native config display hint for generated docs tables.
src/cli_docs_tests.rs New tests to generate/validate docs/cli.md run-flags table and enforce env var bindings.
README.md Streamlines Getting Started, simplifies nav, and replaces registry table with categorized overview tables.
docs/linters.md Renames/reframes linter reference and adds generated overview section + linked headings/configs.
docs/cli.md Replaces hand-written flags list with generated flags+env-var table; moves adaptive-runs content here.
default.json Removes a package rule entry no longer needed.
.github/renovate.json5 Removes README-related custom managers and a package rule entry to match preset changes.
.github/renovate-tracked-deps.json Removes README tracking now that README snippets/version pins were removed.
src/readme_snippets.rs Deleted (README snippet markers/keys no longer used).
src/bin/sync-readme-snippets.rs Deleted (snippet syncing replaced by tests/generation approach).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/cli.md
Comment thread docs/linters.md Outdated
Comment thread src/registry/mod.rs Outdated
zeitlinger added 3 commits May 10, 2026 11:45
@zeitlinger
feat: add agent guidance during init
a9a41e7 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
docs: clarify upstream link availability
a6a9268 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
docs: clarify renovate and changed-file defaults
f90c21a 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
martincostello
martincostello reviewed May 11, 2026
View reviewed changes
Comment thread src/registry/checks.rs Outdated
zeitlinger and others added 2 commits May 11, 2026 12:05
@zeitlinger @martincostello
Update src/registry/checks.rs
8deee24 
Co-authored-by: Martin Costello <martin@martincostello.com>
@zeitlinger
chore: add mise run generate task for regenerating docs
7fa8376 
Replaces raw `UPDATE_README=1 cargo test ...` invocations in test failure
messages with `mise run generate` (README + docs/cli.md + docs/linters.md)
and `mise run generate:snapshots` (tests/cases/*/test.toml). Also updates
AGENTS.md to document both tasks.
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger zeitlinger enabled auto-merge (squash) May 11, 2026 10:55
@zeitlinger zeitlinger merged commit 2d5dcea into main May 11, 2026
12 checks passed
@zeitlinger zeitlinger deleted the docs/linter-reference-overview branch May 11, 2026 11:07
@github-actions github-actions Bot mentioned this pull request May 11, 2026
Merged
zeitlinger pushed a commit that referenced this pull request May 11, 2026
@github-actions
chore: release v0.22.0 (#279)
c3fc3fa 
## 🤖 New release

* `flint`: 0.21.0 -> 0.22.0

<details><summary><i><b>Changelog</b></i></summary><p>

<blockquote>

## [0.22.0](v0.21.0...v0.22.0)
- 2026-05-11

### Added

- replace codespell with typos
([#269](#269))
- *(lychee)* add local cache for local runs
([#268](#268))

### Fixed

- *(renovate-deps)* surface real renovate failure in error output
([#278](#278))
- *(ci)* drop double release-plz update from release:pr
([#276](#276))
- *(init)* normalize node runtime before linters
([#267](#267))
- *(renovate)* support block-scalar mise sha256 values
([#266](#266))
- *(mise)* migrate flint-managed tools to supported backends
([#258](#258))
- validate renovate dependency rule coverage
([#263](#263))
- make flint-setup state-based
([#252](#252))
- *(init)* let rustfmt own Rust line length
([#250](#250))
- run renovate-deps for deleted tracked files
([#247](#247))
- validate CI env and isolate check types
([#253](#253))
- *(init)* remove stale head sha from CI snippets
([#248](#248))
- *(init)* enable yamllint indentation rule
([#251](#251))

### Other

- streamline README getting started
([#280](#280))
- *(deps)* update taiki-e/install-action digest to fa0dd4c
([#282](#282))
- *(deps)* lock file maintenance
([#285](#285))
- *(deps)* update dependency mise to v2026.5.2
([#284](#284))
- *(deps)* update dependency go to v1.26.3
([#283](#283))
- *(deps)* update taiki-e/install-action digest to e3134ec
([#281](#281))
- pass git-token and forge to release-plz
([#274](#274))
- *(deps)* update taiki-e/install-action digest to 3fa6878
([#275](#275))
- *(deps)* bump renovate to 43.150.0
([#273](#273))
- [**breaking**] drop --fast-only flag and tighten renovate-deps timing
([#270](#270))
- *(deps)* update rust crate tokio to v1.52.2
([#272](#272))
- upgrade lychee to v0.24.2
([#265](#265))
- *(deps)* update taiki-e/install-action digest to cca35ed
([#254](#254))
- *(deps)* update dependency aqua:owenlamont/ryl to v0.8.0
([#261](#261))
- *(deps)* update dependency mise to v2026.4.28
([#262](#262))
- *(deps)* update dependency golangci-lint to v2.12.1
([#264](#264))
- *(deps)* update dependency aqua:owenlamont/ryl to v0.7.0
([#259](#259))
- *(renovate)* simplify quickstart and batch weekly linter updates
([#257](#257))
- *(deps)* update dependency npm:renovate to v43.141.6
([#255](#255))
- expand positioning and comparisons
([#239](#239))
- *(deps)* update taiki-e/install-action digest to 1f2425c
([#246](#246))
- move release-plz flow into mise tasks
([#234](#234))
- *(deps)* update taiki-e/install-action digest to 481c34c
([#231](#231))
- *(deps)* update dependency ruff to v0.15.12
([#245](#245))
- *(deps)* update dependency npm:renovate to v43.141.5
([#244](#244))
</blockquote>


</p></details>

---
This PR was generated with
[release-plz](https://github.com/release-plz/release-plz/).

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@martincostello martincostello martincostello approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@zeitlinger @martincostello